---
title: "Overlays"
---

Overlays are used for displaying messages over the top of the grid. There are two built-in overlays: loading and no-rows.

{% warning %}
This page documents the legacy approach to handling overlays. For the latest documentation, see [Overlays Overview](./overlays-overview/).
{% /warning %}

## Loading overlay

{% metaTag tags=["showLoadingOverlay"] /%}

Show or hide the loading overlay by setting the `loading` property to `true` or `false`.

{% apiDocumentation source="grid-options/properties.json" section="overlays" names=["loading"] /%}

The loading overlay takes precedence over the no-rows overlay and is not dependent of the state of `rowData`.

{% gridExampleRunner title="Loading overlay" name="loading-overlay"  exampleHeight=350 /%}

## No rows overlay

When `rowData` is set to an empty array `[]`, the grid automatically displays the no-rows overlay. The no-rows overlay can also be programmatically shown / hidden via the grid API.

{% warning %}
It is recommended to use the [Active Overlay](./overlays-active/) to manually display an overlay.
{% /warning %}

{% apiDocumentation source="grid-api/api.json" section="overlays" names=["showNoRowsOverlay", "hideOverlay"] /%}

The automatic displaying of the no-rows overlay can be suppressed by setting `suppressNoRowsOverlay` to `true`.

{% gridExampleRunner title="No Rows Overlay" name="no-rows-overlay"  exampleHeight=350 /%}



## Initial loading overlay

If `loading` is not explicitly defined, the grid will automatically show the loading overlay until both `rowData` and `columnDefs` are provided with a non-null value for the first time. This behaviour can be suppressed by initialising the grid with an appropriate `loading` state.

## Customisation

Overlays can be customised by providing either a HTML string or custom component via grid properties.


### Custom Loading Overlay

The loading overlay can be customised via the grid properties `overlayLoadingTemplate` or `loadingOverlayComponent` and `loadingOverlayComponentParams`.

{% apiDocumentation source="grid-options/properties.json" section="overlays" names=["overlayLoadingTemplate", "loadingOverlayComponent", "loadingOverlayComponentParams"] /%}

{% if isFramework("javascript", "angular") %}
Implement this interface to provide a custom overlay when data is being loaded.
{% /if %}

{% if isFramework("vue") %}
Any valid Vue component can be a loading overlay component, however it is also possible to implement the following optional methods:
{% /if %}

{% if isFramework("angular") %}
{% interfaceDocumentation interfaceName="ILoadingOverlayAngularComp" config={"asCode":true } /%}
{% /if %}

{% if isFramework("javascript") %}
{% interfaceDocumentation interfaceName="ILoadingOverlayComp" config={"asCode":true } /%}
{% /if %}

{% if isFramework("vue") %}
{% interfaceDocumentation interfaceName="ILoadingOverlay" config={"asCode":true } /%}
{% /if %}

This example demonstrates how to provide a custom loading overlay component customised via parameters.

{% gridExampleRunner title="Custom Loading Overlay Components" name="custom-overlay-loading" /%}

### Custom No Rows Overlay

The no-rows overlay can be customised via the grid properties `overlayNoRowsTemplate` or `noRowsOverlayComponent` and `noRowsOverlayComponentParams`.

{% apiDocumentation source="grid-options/properties.json" section="overlays" names=["overlayNoRowsTemplate", "noRowsOverlayComponent", "noRowsOverlayComponentParams"] /%}

{% if isFramework("javascript", "angular") %}
Implement this interface to provide a custom overlay when no-rows loaded.
{% /if %}

{% if isFramework("vue") %}
Any valid Vue component can be a no-rows overlay component, however it is also possible to implement the following optional methods:
{% /if %}

{% if isFramework("angular") %}
{% interfaceDocumentation interfaceName="INoRowsOverlayAngularComp" config={"asCode":true } /%}
{% /if %}

{% if isFramework("javascript") %}
{% interfaceDocumentation interfaceName="INoRowsOverlayComp" config={"asCode":true } /%}
{% /if %}

{% if isFramework("vue") %}
{% interfaceDocumentation interfaceName="INoRowsOverlay" config={"asCode":true } /%}
{% /if %}

This example demonstrates how to provide a custom no-rows overlay component customised via parameters.

{% gridExampleRunner title="Custom No Rows Overlay Components" name="custom-overlay-no-rows" /%}